Operations Guide

This guide mostly covers installation and maintenance of koji instance. Nevertheless, in few places it inevitably intersects with Administration Guide as some tasks involves also configuration of build tags or external repositories.

• Server Installation
  • Setting Up a Koji Build System
  • Quick Start
  • Knowledge Prerequisites
  • Package Prerequisites
    • On the server (koji-hub)
    • On the database server (koji-hub or separate machine)
    • On the web server (koji-web)
    • On the builder (koji-builder)
    • On the utility server (kojira)
    • On the windows builder (koji-vm)
  • A note on filesystem space
  • Koji Authentication Selection
    • Setting up SSL Certificates for authentication
      • Certificate generation
      • Generate CA
      • Generate the koji component certificates and the admin certificate
      • Generate a PKCS12 user certificate (for web browser)
      • Copy certificates into ~/.koji for kojiadmin
    • Setting up Kerberos for authentication
      • DNS
      • Principals and Keytabs
  • PostgreSQL Server
    • Configuration Files
    • Install PostgreSQL
    • Initialize PostgreSQL DB:
    • Setup User Accounts:
    • Setup PostgreSQL and populate schema:
    • Authorize Koji-hub to PostgreSQL
      • Example: Everything on localhost
      • Example: Separate PostgreSQL and Apache servers
      • Activating changes
    • Bootstrapping the initial koji admin user into the PostgreSQL database
    • Maintaining database
      • Set User/Password Authentication
      • Kerberos authentication
      • SSL Certificate authentication
      • Give yourself admin permissions
  • Koji Hub
    • Configuration Files
    • Install koji-hub
    • Required Configuration
      • /etc/httpd/conf/httpd.conf
      • /etc/httpd/conf.d/kojihub.conf
      • /etc/httpd/conf.d/ssl.conf
      • /etc/koji-hub/hub.conf
    • Authentication Configuration
      • /etc/koji-hub/hub.conf
      • Koji filesystem skeleton
      • SELinux Configuration
      • Check Your Configuration
  • Koji cli - The standard client
  • Koji Web - Interface for the Masses
    • Configuration Files
    • Install Koji-Web
    • Required Configuration
      • /etc/httpd/conf.d/kojiweb.conf
      • /etc/httpd/conf.d/ssl.conf
      • /etc/kojiweb/web.conf
    • Filesystem Configuration
    • Web interface now operational
  • Koji Daemon - Builder
    • Configuration Files
    • Install kojid
    • Required Configuration
      • Add the host entry for the koji builder to the database
      • /etc/kojid/kojid.conf
    • Authentication Configuration (SSL certificates)
      • /etc/kojid/kojid.conf
    • Authentication Configuration (Kerberos)
      • /etc/kojid/kojid.conf
    • Source Control Configuration
      • /etc/kojid/kojid.conf
    • Add the host to the createrepo channel
    • A note on capacity
    • Start Kojid
  • Kojira - Dnf repository creation and maintenance
    • Configuration Files
    • Install kojira
    • Required Configuration
      • Add the user entry for the kojira user
      • Additional Notes
    • Authentication Configuration
      • /etc/kojira/kojira.conf
    • Start Kojira
  • Bootstrapping the Koji build environment
• Koji Server Bootstrap
  • Bootstrapping a new Koji build environment
• Storage Volumes
  • Introduction
  • Constructing the path
  • Symlinks on default volume
  • Adding a new volume
  • Moving builds onto other volumes
  • Using the volume in policy checks
  • Setting a volume policy
  • CLI commands
  • API calls
• External Repository Server Bootstrap
  • Bootstrapping a new External Repo Koji build environment
  • Regenerating your repo
  • Examples of urls to use for external Repositories
    • Fedora 35
    • CentOS 8 and EPEL
  • Example tags and targets
    • Tags
    • Targets
• Koji Kerberos/GSSAPI debugging
  • General problems
• Builder Configuration Options
  • General
  • Building
  • RPM Builds
  • Mock
  • Notifications
  • Kerberos Authentication
  • SSL Authentication
  • Insecure Authentication Options
• Hub Configuration Options
  • File locations
  • File permissions
  • Basic options
  • General authentication options
  • GSSAPI authentication options
  • SSL client certificate auth configuration
  • Notification options
  • Resource limits
  • Extended features
  • Koji hub plugins
  • Koji debugging
  • Hub Policy
  • Koji outages options
  • Name verification
• Database Performance Howto
  • Partitioning
  • Using SSL with PostgreSQL
    • Enabling SSL on the PostgreSQL server
    • Configuring the Koji hub to use SSL to Postgres
• Building Images in Koji
  • Image Building
  • Kickstart First
    • Kickstart Reference
    • Getting your Kickstart to Koji
  • Building LiveMedias
    • Getting Started
    • Mechanics
    • Caveats for LiveMedias
      • %include macros in the kickstart
      • Package Groups in the Kickstart File
      • Only Include RPMs Built in Koji
      • No Signed or Debuginfo RPMs in Koji’s Build Tags
      • %post Section in Kickstart
    • Troubleshooting
    • Build System Preparation
  • Building Disk Images
    • Getting Started
    • OVA Features
    • Kickstart Preparation
      • Required Kickstart Arguments
      • Recommended Kickstart Arguments
    • Troubleshooting
      • Is it a problem with guest creation?
      • Did the installation fail?
      • Did the guest boot?
      • Other Guest Misconfigurations
    • Build System Preparation
      • ImageFactory/Oz Preparation
      • Koji Preparation
  • Building Appliances
    • Getting Started
    • Mechanics
    • Caveats for Appliances
    • Troubleshooting
    • Build System Preparation
• Plugins
  • Runroot
    • Builder
    • Hub
    • CLI
  • Save Failed Tree
    • TODO
  • Sidetag
    • Hub
    • CLI
    • API
  • Proton messaging
  • Image builds using Kiwi
• Koji Utilities
  • Kojira
  • Garbage Collector
    • Prune Policy
    • GC Options (config/commmand-line)
    • Notification related options
    • Server connection options
    • General options
  • Koji Shadow
  • Koji DB Sweeper
• Tasks Description
  • appliance (children: createAppliance)
  • buildMaven
  • buildNotification
  • chainbuild (children: build, waitrepo)
  • chainmaven (children: maven)
  • image (children: createImage)
  • newRepo (children: createrepo)
  • build (children: rebuildSRPM, buildSRPMFromSCM, buildArch, tagBuild)
  • distRepo
  • image
  • indirectionimage
  • livecd
  • livemedia
  • runroot
  • saveFailedTree
  • tagBuild
  • tagNotification
  • vmExec
  • waitrepo
  • winbuild
  • wrapperRPM
  • createKiwiImage
  • kiwiBuild
• Running Koji in Containers
• Supported Platforms
• Releases
  • Koji CVEs
    • CVE-2020-15856
      • Summary
      • Bug fix
      • Links
    • CVE-2019-17109
      • Summary
      • Bug fix
      • Links
    • CVE-2018-1002161
      • Summary
      • Bug fix
      • Links
    • CVE-2018-1002150
      • Summary
      • Workaround
      • Bug fix
      • Links
    • CVE-2017-1002153
      • Summary
      • Bug fix
      • Links
  • Migrations
    • Migrating to Koji 1.27
      • DB Updates
      • Other changes
    • Migrating to Koji 1.26
      • DB Updates
      • Other changes
    • Migrating to Koji 1.25
      • DB Updates
      • Other changes
    • Migrating to Koji 1.24
      • DB Updates
      • Other changes
    • Migrating to Koji 1.23
      • DB Updates
      • Other changes
    • Migrating to Koji 1.22
      • DB Updates
      • Dropped python2 support of hub and web
      • Dropped krbV authentication support
      • Other changes
    • Migrating to Koji 1.21
      • DB Updates
      • Other changes
    • Migrating to Koji 1.20
      • DB Updates
      • Other changes
    • Migrating to Koji 1.19
      • DB Updates
      • Other changes
    • Migrating to Koji 1.18
      • DB Updates
      • More granular permissions
      • Other changes
    • Migrating to Koji 1.17
      • DB Updates
      • Other changes
    • Migrating to Koji 1.16
      • DB Updates
      • Other changes
    • Migrating to Koji 1.15
      • DB Updates
      • Other changes
    • Migrating to Koji 1.14
      • DB Updates
      • Dropped mod_python support
      • Other changes
    • Migrating to Koji 1.13
      • DB Updates
      • Packaging changes
      • Other changes
    • Migrating to Koji 1.12
      • DB Updates
      • Command line changes
      • Configuration
      • RPC API Changes
    • Migrating to Koji 1.11
      • DB Updates
      • Command line changes
      • Client configuration options
      • Other Configuration changes
      • RPC API Changes
    • Migrating to Koji 1.10
      • DB Updates
      • Command line changes
      • Other Configuration changes
      • RPC API Changes
    • Migrating to Koji 1.9
      • DB Updates
      • Command line changes
      • Other Configuration changes
      • RPC API Changes
    • Migrating to Koji 1.8
      • DB Schema Updates
      • Migrating your old images
      • Cleaning up
      • Command line changes
      • New kojira options
    • Migrating to Koji 1.7
      • DB Schema Updates
      • mod_python and mod_wsgi
        • Migrating to mod_wsgi
        • Staying on mod_python
      • Web Configuration
        • Custom Config File Location
      • Changes to url options
      • Additional Notes
        • Split Storage
        • Web Themes
  • Release Notes
    • Koji 1.27.0 Release notes
      • Migrating from Koji 1.26/1.26.1
      • Security Fixes
      • Client Changes
      • API Changes
      • Builder Changes
      • System Changes
      • Web
      • Utilities
        • Kojira
      • Documentation
    • Koji 1.26.1 Release notes
      • Migrating from Koji 1.26
      • Security Fixes
      • Client changes
      • Hub Changes
      • Builder changes
      • Kojivmd
      • Documentation/DevTools Changes
    • Koji 1.26.0 Release notes
      • Migrating from Koji 1.25/1.25.1
      • Security Fixes
      • Client Changes
      • API Changes
      • Builder Changes
      • System Changes
      • VM
      • Web
      • Plugins
      • Utilities
        • Kojira
        • Sweep DB
      • Documentation
    • Koji 1.25.1 Release notes
      • Migrating from Koji 1.25
      • Security Fixes
      • Library changes
      • Hub Changes
      • Web Changes
      • Documentation/DevTools Changes
    • Koji 1.25.0 Release notes
      • Migrating from Koji 1.24/1.24.1
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • System Changes
      • Web
      • Plugins
      • Utilities
        • Kojira
        • Garbage Collector
      • Documentation
    • Koji 1.24.1 Release notes
      • Migrating from Koji 1.24
      • Security Fixes
      • System Changes
      • Library changes
      • CLI changes
      • Hub Changes
      • Web Changes
      • Utilities Changes
      • Documentation/DevTools Changes
    • Koji 1.24.0 Release notes
      • Migrating from Koji 1.23/1.23.1
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Builder Changes
      • System Changes
      • Web
      • Plugins
      • Utilities
        • Kojira
      • Documentation
    • Koji 1.23.1 Release notes
      • Migrating from Koji 1.23
      • Security Fixes
      • System Changes
      • Library Changes
      • Hub Changes
      • Builder Changes
      • Web Changes
      • Utilities Changes
      • Documentation Changes
    • Koji 1.23.0 Release notes
      • Migrating from Koji 1.22/1.22.1
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Builder Changes
      • System Changes
      • Plugins
      • Utilities Changes
        • Kojira
      • Documentation
    • Koji 1.22.1 Release notes
      • Migrating from Koji 1.22
      • Security Fixes
      • Library changes
      • Hub Changes
      • Builder Changes
      • API Changes
      • Documentation Changes
    • Koji 1.22.0 Release notes
      • Migrating from Koji 1.21/1.21.1
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Builder Changes
      • Web UI Changes
      • Win Builder Changes
      • System Changes
      • Plugins
        • sidetag
      • Utilities Changes
        • Garbage Collector
        • Kojira
        • koji-sidetag-cleanup
        • koji-sweep-db
    • Koji 1.21.1 Release notes
      • Migrating from Koji 1.21
      • Security Fixes
      • Client Changes
      • Library changes
      • Hub Changes
      • Utilities Changes
        • Garbage Collector
        • Kojira
      • Documentation Changes
    • Koji 1.21.0 Release notes
      • Migrating from Koji 1.20
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Builder Changes
      • System Changes
      • Plugins
      • Utilities Changes
        • Garbage Collector
        • Kojira
      • Documentation Changes
    • Koji 1.20.1 Release notes
      • Migrating from Koji 1.20
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Web UI Changes
      • Builder Changes
      • System Changes
      • Utilities Changes
        • Garbage Collector
        • DB Sweeper
        • Kojikamid
      • Documentation Changes
    • Koji 1.20.0 Release notes
      • Migrating from Koji 1.19
      • Security Fixes
      • Client Changes
      • Library Changes
      • API Changes
      • Web UI Changes
      • Builder Changes
      • System Changes
      • Utilities Changes
        • Garbage Collector
        • DB Sweeper
        • Kojikamid
      • Documentation Changes
    • Koji 1.19.1 Release notes
      • Client Changes
      • System Changes
    • Koji 1.19.0 Release notes
      • Migrating from Koji 1.18
      • Security Fixes
      • Client Changes
      • Library Changes
      • Web UI Changes
      • Builder Changes
      • System Changes
    • Koji 1.18.1 Release Notes
      • Issues fixed in 1.18.1
    • Koji 1.18.0 Release notes
      • Migrating from Koji 1.17
      • Security Fixes
      • Client Changes
      • Library Changes
      • Web UI Changes
      • Builder Changes
      • System Changes
    • Koji 1.17.0 Release notes
      • Migrating from Koji 1.16
      • Security Fixes
      • Client Changes
      • Library Changes
      • Web UI Changes
      • Builder Changes
      • System Changes
    • Koji 1.16.2 Release Notes
      • Issues fixed in 1.16.2
    • Koji 1.16.1 Release Notes
      • Issues fixed in 1.16.1
    • Koji 1.16.0 Release notes
      • Migrating from Koji 1.15
      • Security Fixes
      • Client Changes
      • Builder Changes
      • System Changes
    • Koji 1.15.1 Release Notes
      • Issues fixed in 1.15.1
    • Koji 1.15 Release Notes
      • Updates
      • Migrating from the previous release
      • Client Changes
        • Display license Info
        • Keytabs for GSSAPI authentication
        • Add krb_canon_host option
        • Watch-task return code
        • New runroot options
        • New watch-logs options
      • Web UI changes
        • Archive component display
        • Display license Info
        • Show suid bit
      • Builder changes
        • Alternate tmpdir for mock chroots
        • Store git commit hash
      • System changes
        • Volume policy support
        • Messagebus plugin changes
          • Deferred sending
          • Test mode
        • Protonmsg plugin changes
        • No notifications for disabled users or hosts
        • Replace pycurl with requests
        • Drop importBuildInPlace call
    • Koji 1.14 Release Notes
      • Migrating from Koji 1.13
      • Client Changes
        • Fail fast option for builds
        • Custom Lorax templates
        • Allow profiles to request a specific python version
        • New list-builds command
        • New block-group command
        • Exit codes for some commands
        • Easier for scripts to use activate_session
      • Builder changes
        • Normalize paths for scms
        • Graceful reload
        • Friendlier runroot configuration
      • System changes
        • Deprecations
        • Removed calls
        • Dropped mod_python support
        • Large integer support
        • Test mode for protonmsg plugin
        • Handling of debugsource rpms
        • Added kojifile component type for content generators
    • Koji 1.13 Release Notes
      • Migrating from Koji 1.12
      • Client Changes
        • Python 3 client support
        • CLI Plugins
        • list-channels CLI command
        • hostinfo CLI command
        • Enhancements to restart-hosts
        • User-Agent header
        • raise error on non-existing profile
      • Changes to the Web interface
        • Build Log Display
      • Builder changes
        • Configuring mock chroot behavior
        • pre/postSCMCheckout callbacks
        • Extended allowed_scms format
      • System changes
        • mod_auth_gssapi required
        • Longer tag names